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DATE: June 3, 1983 

TO: NOS Section 

FROM: G. A. Kersten 

SUBJECT: NOS Coding Standards 

Attached is the new "NOS COMPASS Programming Standard" and the new "NOS SYMPL 
Coding Standard" for the NOS Development Section. These versions replace all 
previous versions of the standards. 

Many additions, changes and clarifications have been included from suggestions 
received from the Design Support Team (DST) and from others during the 
preparation of these revisions. Change bars in the right hand columns mark 
the majority of the changes (some minor wording changes are not marked). 

Major changes in the COMPASS standard include: 

* Documentation of the PP instruction and jump macro usage (MJP, PJP, ADK, 
LDK, etc.). 

* Suggestions for hangs and error processing to assist in debugging. 

* Description of the new ISTORE macro and its use for instruction 
modification. 

* Use of BSS vs BSSN. 

* Use of ^SYSTEM XXX,=" and "EXECUTE XXX,=" macros for cross reference 
purposes. 

* Reservation of tags beginning with "U" for installation use. 

* Clarification of the use of REQUIRES line in a modset. 

* Additional interface considerations. 

* A new Appendix - "DOCUMENTATION/USABILITY GUIDELINES". 

Major changes in the SYMPL standard include: 

* Deleting the MSF Project Addendum and incorporating many of the items into 
the standard. 

* Addition of the Screen Management Facility (SMF) Project Addendum. 

Any questions or comments should be addressed to the Design Support Office 
(DSO) or members of the DST. Requests for changes to the standards should 
follow the procedure defined in the NOS Section Procedures Notebook. Several 
suggestions were made as a result of section code review and resulting changes 
will be incorporated into the next revision of the standards. 



G. A. Kersten 
Design Support Team 
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1 . IN TEODUCTIC N 

1.1 SCOPE OF DOCUMENT 



1.1.1 PURPO SI 

This document establishes standard procedures to be used ly 
programmers in the development and maintenance of programs in 
COMPASS Assembly language. 

This document shculd be used ty programmers as a reference manual of 
standard programming procedures. The implementation of these 
procedures will increase the efficiency cf program development/ 
improve the reliability and maintainability cf the program and aid 
in the training cf persons who will be maintaining or using the 
program . 



1.1.2 SCOPE_OF_USE 

The procedures defined in this document are applicable tc the 
NETWORK OPERATING SYSTEM (NC£) and its related subsystems. 



1.2 CONFORM A KCE_ANB_ENFORCEJiENT 

The procedures defined in this document are to be used in all newly 
developed programs. In existing programs these procedures should be 
used if they are net inconsistent with the existing procedures. If 
major changes (such as a rewritten subroutine or a new overlay) are 
made to a program, these procedures are tc te used for the changes. 

Programs which do net conform to these requirements will be returned 
to the programmer for correction. 
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2.0 DOCUMENTATION 



2.1 IMIODUCTION 

Documentation is the presentation cf information about a program in 
easily understandable form sc that these who need to understand the 
program do not need to study the program itself. This reduces the 
time consumed frcm days or weeks to just minutes or hours. 

The program documentation presente.d_ in this standard is embedded 
within the source language cf each program. The documentation is , 
designed to be extractable by the standard documentation processing 
program, DOCKENT. This approach serves to unify the program and its 
documentation, making it easier and more natural to update the 
documentation as changes are made to the cede. 

The effectiveness cf documentation is judged by its success in 
meeting the needs cf those who use it. This introduction defines 
four distinct needs for documentation which arise during the life of 
a software product. Sections 2.3 through 2.E define three levels of 
documentation (Program Level, Subroutine level and Cede Level) which 
together meet these needs. 

Section 2.7 gives examples cf proper documentation. 

2.1.1 DES IG N_0 VE E V JEH 

Anyone wanting to knew the structure of the system, cr seme 
functional area, dees not want excessively detailed information 
which will make the task mere difficult. Cne should be able to ask 
the question: 

What is the function cf this program? 

and get an answer that is brief arid to the point. It should not 
contain any information about the input parameters, options, error 
conditions, or internal workings cf the program. 

2.1.2 EXTEENAL_ INTERFACE 

Anyone who knows the function cf a program and wants to knew how to 

interface to the program needs to knew the form of the call, what 

parameters to supply, what information is returned, and what is 
accomplished. One should be able to ask the question: 
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How is this program used? 

and get an answer that lists the parameter definitions, formats, and 
contents, the initial conditions cf huffers and devices, any status 
and condition information, a list cf other programs called, and a 
complete list of errcr codes, error messages issued and parameters 
returned. A general description cf the actions taken should be 
included for each function performed that is recognizable by the 
calling program. 



2.1.3 IHEENAL_ OPERATION 

Anyone working en a modification or enhancement to the system needs 
a general knowledge cf the internal operation of a program. This 
requires finding cut where within the program some function is 
performed and how it is performed. Cne should be able to ask the 
question: 

How does this program work? 

and get an answer that includes a description cf the logical flow 
and structure cf the program, the algorithms used and the function 
performed by each overlay or sutrcutine in the program. 

2.1.4 DETAILED CCDE ANALYSIS 

Anyone attempting to modify the program or establish a knowledge of 
the detailed operation of a program uses tre listing. Documentation 
should be provided in the listing to aid in following the flow of 
the program without reading all cf the cede. This documentation 
consists of comments within the cede itself. Comments describing 
the function of logical groups cf instructions should be provided, 
and comments documenting table structures, data areas, and constants 
should appear on the instructions which define them. One should be 
able to ask the question: 

What should I know when modifying this program? 

and get back an answer with all the detail needed to make the 
modifications without adversely affecting existing program functions 
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2 . 2 GE N EB1L_RE£UI EEIIITS 

2.2.1 ABBREVIATIONS 

The abbreviations for technical terms which are to be used in 
program documentation are listed in Appendix A. All other technical 
words and phrases are completely spelled cut. Routine names and 
mnemonic names of tables and equipments are not considered 
abbreviations. 

A program whose documentation makes - extensive use of terms not in 
this list may define a list cf abbreviations and include it in the 
first section of the internal documentation for the program. Such 
abbreviations may net be used in the program overview or external 
documentation. v 

The following standard symbols are used in the documentation when 
expressing logical and arithmetic comparisons: 

.NOT. logical inverse 

.XOR. logical difference (exclusive or) 

.AND. logical product 

.OB. Logical sum (inclusive or) 

.EQ. equal to 

. NE. Net equal to 

.LE. Less than or equal tc 

.GE. Greater than cr equal tc 

.LT. Less than 

.GT. Greater than . - 

= equal to 

() contents of 

(()) contents of the contents of (indirect addressing) 

2.2.2 PUNCTUATION 

All documentation and comment lines contain complete English 
sentences with correct punctuation. Exceptions are allowed in 
subroutine headings (see section 2.4) and in embedded comments (see 
section 2.5.2). Titles (such as "Assembly Constants.") should end 
with a period but need not be complete sentences. Each comment 
(excluding embedded comments) should end with a period even if it is 
not a sentence. 

Correct punctuation means the same punctuation as required in 
written English. However, the apostrophe presents problems due to 
character set and print train differences, and plurals cf 
abbreviations are not readable i»ithout upper and lower case. 
Therefore, plurals and possessive forms cf abbreviated terms are to 
be avoided. Authori2ed abbreviations (see section 2.2.1) are made 
plural by adding a hyphen and the letter "s" (e.g. PP-S). 
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If an upper case item is to be indicated in the documentation, it is 
enclosed within asterisks. Upper case is used for names of files, 
programs, calling parameters, sufcrcutine tags, table names and any 
other vords that are normally capitalized . Accepted abbreviations, 
acronyms, and programming language names are not enclosed in 
asterisks even if they would normally be capitalized (refer to 
Appendix A and section 2.2.1). Tables defined in CHR do not need 
asterisks (EJT, QFT, etc.). 

2.2.3 FOMMS 

Documentation lines contain cnly asterisks and blanks in the first 
ten columns and text in columns 11 through 71. The text is written 
using correct -English except where specifically noted. The format 
for each of the various types cf documentation is shewn below. 
Later sections define the usage cf each type of 
documentation. 



External 



Asterisks in columns 1 through 3 (***). 
This line indicates that this and the . 
following contiguous comment lines are to be 
included in the prcgram external 
documentation. 



Internal 



Asterisks in columns 1 and 2 (**). This 
line, indicates that this and the following 
contiguous comment lines are to be included 
in the prcgram internal documentation. 



Internal Bracket 



Asterisks in columns 1 through 4 (****). 
This line and all ether lines up to and 
including the next occurrence cf this line 
are to he included in the prcgram internal 
docuEentaticn. 



Other Comment 



Asterisk in column 1 (*). This type of 
comment is used for continuation cf the 
above types cf dccuitentaticn. It is also 
used for stand-alone comments (see section 
2.5.1). 



Table 
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Asterisk in column 1, I in column 2 (*T). 
This line indicates the beginning cf table 
documentation. The *T lines must appear 
within consecutive comment lines beginning 
with an external (***) or internal (**) 
statement. DCCMENT generates a table 
diagram from the field widths and 
descriptions in the *T documentation. Note 
that the field description size (including 
blanks) cannot exceed the field width size 
(to prevent truncation). A DOCMEM listing 
should be made of a program's 
external/internal documentation when table • 
structures are added (to verify correctness). 
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Table Continuaticn - Asterisk in column. 1, T in column 2, comma 

in column 3 (*T,). This type of comment is 
used for continuation of table documentation 
started ly a *T line. 

Blank Comment Line - A line with an asterisk in column 1 (*) and 

blanks in columns 2 through 71 is called a 
"Blank Comment line cr "Blank Comment Card" 
and is used as a separator to improve 
readability cf dccum entaticn. 

2.2.4 FOR M A T_OF_ I TE M IZED_DCC UME NT AT 1CN 

Documentation which contains several separate items cf information 
(as found in sections 2.3.1, 2.3.2, 2.3.3 and 2.4) contains a Blank 
Comment Line between the items. Each item ends with a period. If 
an item is not applicable , it is emitted frcn the documentation. The 
items are placed in the order specified and the last item is 
followed by a SEACE 4,10 line. 

2.3 PR0GRAM_LEVEI_E0CUKEN1MICN 

Every program contains comment lihes which make up the Program Level 
documentation (as defined .in this section). This level cf 
documentation may be used with the program listing or without it 
(using extracted documentation produced .by a documentation 
processor). Even without the listing, the Program Level 
documentation satisfies the Eesign Cverview, External Interface and 
Internal Operation documentation needs discussed in section 2.1. 



2.3.1 OVERVIEW 

The overview documentation is placed immediately following the 
COMPASS Group 1 instructions and befcre any ether documentation, 
macro definitions cr executable cede (see section 3.2). It consists 
of an external documentation line (see section 2.2.3) which contains 
the program name and a brief description cf the program, and 
additional comment lines which contain the following items of data 
(see section 2.7 fcr the laycut cf these items): 

Name of author and date written (yy/mm/dd). 
. Names of authors of major modifications, with dates. 
Text of cverview of program. 

The text of the cverview should follow the general definition of 
Design Overview documentation in section 2.1. The objective is to 
describe the function of the program in general terms. 
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2.3.2 EXTEENftl 

The external documentation is placed immediately following the 
overview dccumentaticn and fcefcre any internal dccumentaticn, macro 
definitions or executable cede (see section 3.2). It consists of an 
external documentation line (see section 2.2.3) and additional 
comment lines which together certain the following items of data 
(see section 2.7 fcr the laycut cf these items): 



Detailed description cf functions and options. 

Entry conditions, including parameters and initial 

conditiens cf buffers and external' tables . 

Command format. 

Exit conditions, including status tits and fields returned. 

Errors detected, error cedes returned, including subsequent 

action taken fcr each. 

System errors detected and subsequent action taken. 

Other programs called. 

Messages issued (including dayfile and operator). 



The content of this section follows the general definition cf 
External Interface documentation in section 2.1. The objective is 
to supply information required ty a potential user of the program. 

2.3.3 INTEEOL 

The internal documentation describes the internal workings cf the 
program. It may be dispersed throughout a progxam as desired, 
however a major portion appears imrnr'''' ■=->->--\ ^ ^H"«^" *-*>'~ ^ ■<»■■»•«■ 

ion consists cf an internal 

:ards 



System texts required fcr assembly (other than default). 

Direct cell usage (PP programs). 

Global register assignments (CEU programs). 

Data areas and table formats. 

Memory map (if overlays are used). 



Other items to be included if applicable are: 

. Techniques cr algorithms employed where not obvicus. 
Timing considerations. 
Interlock considerations. 

Known limitations tc perfcrmance cr extensibility, such as 
timing cf loops, core size, errcr-recovery deficiencies. 
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Any other information which would aid someone in understanding the 
internal workings cf the program is also provided, including logical 
flew, structure, and pitfalls tc redesign. 

2 . 4 SUBR OUT IIE_LEVIL_DCCUME STATIC N 

i 
The heading of any subroutine consists cf comment lines giving a 
brief description cf its function, its entry and exit conditions, 
register or direct cell usage and internal workings. The 
information contained should be en a level indicated by the 
complexity of the subroutine. Ihe following items of data should be 
included (see sections 2.7.2 and 2.7.3 for the layout of these 
items) : ' '» 



TITLE line with name as surtitle (primary subroutine) 

SPACE line (see section 3.6.3) 

Internal comment line giving name and title of subroutine 

One or mere sentences describing the function of the 

subroutine (optional but desiratle). 

Entry conditions (list) 

Exit conditions (list) 

Error exit conditions (list) 

Register or direct cell usage (list) 

Routines called (list) 

Macros called (list) 

Description of allocated registers 

Timing considerations, if critical 

Design, implementation and general information 

Two blank lines 



The title of the subroutine should describe the action performed by 
the subroutine (for example, Pcsiti.cn Mass Storage, Make Queue 
Entry). This means that titles shculd always contain a verb. 
Titles without verts should be used for groups of subroutines and 
COMSxxx decks. 

Defined formats exist for the list cf items in the subrcutine 
heading. A keyword appears in column 11, followed by text in column 
18. The text is simply a list, rather than complete sentences. Any 
list requiring mere than one lire is continued beginning in column 
18 (or beyond) of the next comment line. The formats are shown 
below. Each list ends with a pericd. acceptable keywords include: 

ENTRY ' Entry conditions. 

EXIT Exit conditions. 

ERROR Error exit conditions. 

USES Register or direct cells destroyed. 

CALLS Routines called. 

XREF Common or system decks required. 
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MACROS Hacrcs called. 

DEFINE list of allocatable registers. 

TIMING Description of timing considerations. 

NOTES Programming information. 

Documentation for common decks and zero level overlays shculd 
include subroutine level documentation where appropriate. 

2.4.1 ENTE Y_CO N D I TION S_1ENI 111 

Entry conditions include the fcllcvlng" items : 

Eegisters, direct cells or memory locations that must be set before 
the subroutine is called. 

logical status of channels, files, etc., (i.e. Channels reserved, 
files set busy, disk pcstioned, files positioned) that shculd exist 
before the subroutine is called. 

Only one entry condition may be specified per line. For EF code, 
the contents of the £ register should be described first. 

2.4.2 EXIT_C0NDITICNS_iEXIT2 

Exit conditions include the following items: 

Eegisters, direct cells or memory locations that may be used by 
subsequent routines. 

Logical status ,of channels, files, etc., (i.e. Channels reserved, 
files set busy, disk positioned, files pcstioned) that exist when 
the subroutine is exited. 

Only one exit condition is listed per line. For PP code, the 
contents of the A register should be described first. 

Branches (not CAlIs) to other routines. 

2.4.3 EREOE_EXI T_ CCN 1CIT ION S_1EH E C E2 

Error exit conditions include all exit ccnditions that exist when a 
special termination of the subroutine, such as a jump to an error 
processor, is taken. Error conditions include the following items: 

The label being jumped to and the conditions that caused 
the special exit. 

/ 
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» Registers, direct cells cr memory locations that may be 
used by subsequent routines. 

logical status of channels, files, etc., (i.e. Channels 
reserved, files set busy, disk positioned, files postioned) 
that exist when the subroutine is exited. 

Only one exit condition is listed per line. The label being 

jumped to is documented first with all exit conditions pertaining 
to that exit following. If these are multiple error exits, each 

with unique conditions, the conditions should be listed under their 
own exits. 



2.4.4 R EGI S 1EE_C E_EI BECT_CE I 1_I) S AG £_i U S IS I 

Registers or direct cells used include all registers or direct cells 
destroyed by that subroutine only. Eegisters or dirept cells 
destroyed by subroutines or KACBCS called by a routine are not 
listed; ,- 

For CPU code, the format of the USES bicck includes a register type 
(X - operand register, A - address " register , B - index register) 
followed by a sequence of ascending numrers indicating the registers 
used. The term ALL may be substituted if all registers are used by 
a routine . 



Example: 






* 


USES 


X - 0, 1, 6. 


* 




A - 1, 6. 


* 




E - 3, 7. 



Indicates the following registers are used: 
X0, X1, X6, A1, A6, B3, E7. 

For PP code, single direct cells are listed in alphabetical order 
followed by multiple direct cells listed in alphabetical order. 

Example : 

* USES T1, T2, T5, CM - CK+4, EI - RI+4. 

The direct cell at PP memory location (TO) is assumed to be used 
by every subroutine unless otherwise stated in the ENTRI/EXIT 
conditions. This is because certain instructions, such as CRM and 
CWK, destroy location zero. 
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2.4.5 ROUTINES_C^LIEE_XCALLSi 



common 



Routines called by a subroutine include all subroutines, 
decks and overlays that -are explicitly called. Routines called by 
macros are not tc be included. Where the rcutine called dees not 
return to the calling point, the branch is an EXIT condition rather 
than a CALL. 

2.4.6 CCMCN^R_SYSTEM_DECKS_SE£UIRED_1XEEFJ 

i 

When a routine, iracrc, or cemmen deck requires a particular common 
or system deck fcr assembly cr for correct execution, it is valuable 
to list the deck(s) required. 

Example: 

* XEEF CCMCLCD, CCKCRTN. 

2.4.7 MACE0S_CALIED_1MACR0S2 

Macros called include all macros that are explicitly called by a 
subroutine. The SUES macro is always implied to be called and need 
not be listed. FP macros ADK, IDK, LMK, IPK, SBK, MJP, NJP, PJP, 
UJP, and ZJP need not be listed. 

2.4.8 A LLOC A TED_ E E G I S TE ES_C E_ E I EE C 1_ C EL I S_X lllllll 

Allocated registers are registers (or direct cells fcr PP code) used 
for well defined items throughout a particular subroutine cr program, 

2.4.9 TIKING_CCNSIDERATIONS_lTIMINGi 

Timing considerations should describe any timing limitations that 
are imposed on the subroutine tecause cf hardware or performance 
constraints. Care should be taken tc express units cf time in a 
manner independent of machine tjpe. For example, units of time 
expressed in cycles rather than microseconds is more desirable. 
This is because the same rcutine may execute faster cr slower than 
stated depending on the type of the EP cr CPD it executes in. 

2.4.10 PROGRAMMING NCTES (NOTES,) 

This section documents design, iuipleirenta ticn and general 
information that may be useful tc ether analysts. Information in 
this section pertains to the subroutine only. 
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2.5 CODE_LEVEL_DCCUMENTATICll 

All documentation which is net described in cne of the preceding 
sections of this document falls into the category of Code level 
documentation. The requirements for this type of documentation vary 
widely, so few rules can be stated; hewever, Code Level 
documentation is necessary and the lack cf explicit requirements 
must not lead to its neglect. 

Code Level documentation/ alcng with the sufcroutine headings, must 
satisfy the need for aid in readingthe cede. Its content follows 
the guidelines fcr retailed Cede Analysis in "section 2.1.4. 

2.5.1 STAN£;;IiCNE_COKHENTS 

Stand-alone comments are comment lines appearing in-line with code, 
as opposed to within higher-level documentation previously defined. 
All stand-alone comments are preceded and followed by one blank 
line. To reduce the binary size cf systems texts, stand-alone 
comments within macro definitions should be preceeded and followed 
by a blank comment line. 

Stand-alone comments describe the functicn performed by the 
subsequent section of in-line cede. The cemments are complete 
English sentences with correct punctuation, ending with a period. 
The comments refer tc functions and data in external terms, rather 
than only in octal numbers and tit pesitions. These comments follow 
the general requirements found in section 2.2. 

2.5.2 EMBEE£E£_CCKKEKTS 

Embedded comments are comments in columns 3G-71 of a line assembled 
by COMPASS, not a comment line. The comment need not be a complete 
sentence and is net terminated with a period. This type cf comment 
is never continued onto another line. If the intended comment is 
too long to fit en the single line, it is inserted as a stand-alone 
comment preceding the area of cede tc which it applies. Care should 
be taken not to cverflow into cclumn 72. 

An embedded comment describes the functicn cf the instruction or 
sequence of instructions on which it appears. (It must be at the 
beginning cf the sequence.) It dees net describe the hardware 
operation being performed, but rather its meaning in the context of 
the functicn to be performed by the program. 
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With the excepticn cf extremely complex cede, it should net be 
necessary to put embedded comments on every line. Frequently, it is 
advantageous to emit "obviotis" cr redundent comments, since it then 
becomes easier fcr the casual reader tc scan the routine. 

An embedded comment is reguired on each jump instruction, to 
identify the condition being tested (ccnditicnal jumps) cr the 



action being taken (unconditional jumps). Cn 
word "JUtfP" is superfluous, and is net used, 
the comment must begin with the wcrd "IF" and 
condition on which the jump will be executed, 
the general requirements found in Section 2.2. 



jump instructions, the 
Cn conditional jumps, 
describes the 
These comments follow 



An embedded comment is required on all pseudc tests (ERRNZ, EREPL, 
etc.). The comment should state- the condition fcr which the test 
. . . , .,„. , - " - - ■ fc 6 U ced. 



fails and the word "IF" should not 



Example - EBENG *-BUEAL CCEE CVEFFLOWS BUFFER AEEA 

2 . 6 MACRO_IEVEL_B CCU HEN2MIC N 

The heading of any macro definition consists of comment lines giving 
a brief description of its function, its entry and exit conditions, 
register or direct cell usage and internal workings. The 
information contained should be cn a level indicated by the 
complexity of the macro. .The fcllcwing items of data should be 
included (see section 2.7.4 fcr the layout -cf these items): 

SPACE line (see section 3.6.3) 

Internal comment line giving name and title of macro 

One or more lines cf text explaining the purpose and/or 

function cf the macro (optional but desirable). 

Format cf macro call 

Entry conditions (list) 

Exit conditions (list) 

Begister cr direct cell usage (list) 

Boutines called (list) 

Macros called (list) 

Two blank lines : 

Defined formats exist for the list cf items in the macro heading. 
A keyword appears in column 11, fcllcwed by text in column 18. The 
text is simply a list, rather than complete sentences. Any list 
requiring more than one line is continued beginning in column 18 (or 
beyond) of the next comment line. The fcrirats are shown below. 
Each list ends with a period. 
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ENTRY Entry conditions. 

EXIT Exit conditions . 

USES Register or direct cells destroyed. 

CALLS Routines called. 

MACROS Macros called. 

2.6.1 EN2RJf_C0NCITICSS_!ENTRY2 

Entry conditions may include the following items: 

Description of macrc parameters that are allowed. Complete 
descriptions of macro parameters include: 
1 .. valid parameter options 

2. default values cf parameters 

3. register optimization, if applicable 

Registers, d.irect cells cr iremcry locations that must be 
set before the macrc is called. Entry conditions may refer 
to the entry documentation found in subroutines called by 
the macro. 

Logical status of channels, files, etc., (i.e. Channels 
reserved, files set busy, disk jccstioned, files positioned) 
that should exist before the macrc is called. 

Only one entry condition may be specified per line. For FP code, 
the contents cf the A register should be described first. 

2.6.2 EX IT_C0NB I T IC N S_1EXIT1 

Exit conditions include the following items: 

Registers, direct cells cr iremcry locations that may be 
used by subsequent routines. Exit conditions may refer to 
exit conditions in subroutines called by the macro. 

logical status of channels, files, etc., (i.e. Channels 
reserved, files set busy, disk positioned, files postioned) 
that exist when the code generated by the macro is exited. 

Special terminations cf the macrc such as jumps to error 
processors cr to any other routines. The label being 
jumped to and the conditions that cause the special exit 
should te documented. 

Only one exit condition is listed per line. For PF code, the 
contents of the A register should be described first. 
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2.6.3 1EG ISTER_CP_E I EECT_CE LI_U S AGE_XUS ES2 

Registers or direct cells used Include all registers or direct cells 
destroyed (or modified) by that -nacre only. Refer tc section 2.4.4 
for the format of the USES block. 

2.6.4 R0UTIIES_CAL1EB_XCALLS2 

Routines called fcy a macro include all subroutines and overlays that 
are explicitly called. Routines called fcy macros ■ within the macro 
definition are net tc be included. 

2.6.5 I ACRC S_C A 1 1 ED_1 KA CR OSJ 

Macros called include all macros that are explicitly called by a 
macro definition. -.. . 



2.7 DOCUMENTATION. ..EXAMPLES 

These examples are statements cf the standard and are intended as 
further clarification cf the required procedures. 

2.7.1 PROGRAM_LEVEI 

*** LIEEEIT - LIBRARY EDITING FBCGEAH. 
* 

* A. E. ORIGINAL 74/C1/C1. 

* A. E. MODIFIES* 75/01/01. 

* C. D. MODIFIER. 76/01/01. 
SF£CE 4,10 

♦LIBEDIT* IS A GENERAL PURPOSE FILE EDITING 
PROGRAM CAPABLE CF MODIFYING AND GENERATING 

* LIBRARY FILES. 
SPACE 4,10 



*** 
* 



** * 

* 
* 



COMMAND FORMAT. 



SPACE 4,10 
DAYFILE MESSAGES. 
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*** 

* 

* 



SPACE 4,10 

ACCOUNT FILE r MESSAGES. 



*** 

* 

* 



SPACE 4,10 

EBECR LOG MESSAGES. 



*** 

* 
* 



SPACE 4,10 
CFEEATCR MESSAGES. 



BUFL 
* * * * 



SPACE 4,10 
COMMON DECKS. 



SFACE 4,10 

MACEC DEFINITIONS 



ASSEMBLY CONSTANTS. 



EQU 



1001B 



SPACE 4,10 
GLCBAL STORAGE. 



CUTPUT BUFFER LENGTH 



2.7.2 SUBP.OUTINE_LEV EL_iPP_CCDE J 



LEM 
* * 

* 

* 

* 
* 

* 



TITLE ERROR FEOCESSING RCU1INES. 

SPACE H,30 

LEM - IIST ERECR MESSAGE. 

*LEM* ISSUES EERCE MESSAGES IC THE JOB ANE 
SYSTEM DAYFILES AND TO THE EBECR LOG. 

ENTRY (A) = 1 IF SINGLE EIT SECDED ERROR. 
= 2 IF STATUS/CCN1RCL REGISTER 
EBECR LIMIT. 
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* 
* 
* 

* 
* 
* 

* 
* 

* 



(SCEA - SCEA+20) = SCR IMAGE. 

(NL) = ADDEESS CF NEXT LIST ENTRY. 

EXIT (SI) = UPDATED LIST EC INTER. 

ERBCR TO *EEB* IF EEECR ENCCUNTERED. 

USES T1, T2, CM - CM+4, FN - FN+4. 



* CALLS LMC. 

* 

* XEIF CGHPABZ. 

* 

* MACECS MONITOR. 

* 



DEFINE (T2)< = FNA CF MESSAGE. 
* 

* TIMING A DELAY IS NEEDED TC AVCID FILLING TEE 

* DISK WITH EEECE LOG MESSAGES. 

LEM SUEE ENTEY/EXIT 

*>. 

•■■ 

UJN LEMX. EETURN 



2.7.3 SU ESCUTI N E_LE VEL_iCP_CODE2 

ACS SPACE 4,25 

** ACS - ASSEMBLE CHARACTER STRING. 
* 

* *ACS* ASSEMBLES A CHARACTER -STRING INTC BUFFER 

* *CEUF*, PACKED 10 CHAEACTEES PER CM WOBD. 

* ENTEY (B6) = FWA CF CEAEACTEE STEING. 

* (E7) = IENGTH CF STEING BUFFER. 

* 

* EXIT (CBUF - CELE+2C) = CHAEACTEE STEING. 
* 

* EEECE TO *EBE* IF INVALID CEAEACTER FCUND. 

* (X1) = FWA CF EERCE MESSAGE. 



* USES X - 0, 1, 6. 

* A - 1, 6. 

* B - 6, 7. 
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* CALLS MCI. 

* 

* MACROS GETCH. 
* 

* DEFINE (XO) = CHAEACTEE MASK. 



ACS SUER ENTEY/EXIT 



EQ ' ACSX RETURN 



2.7.4 MACRC_LEVEI_DCCUMENTATICN 

ERROR SPACE 4,10 

** ERROR - ERROR PROCESSING KACRC. 

* 

* . EEECE ADDR 

* 

* ENTRY *ADDR* = FViA CF DAYFILE MESSAGE. 
* 

EXIT. TC *EFR*. 

* 

* USES X - 1. 



PUEGMAC ERROR 

ERROR KACRC A 

SX1 A 

EQ EPR 
ERROR ENEM 
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3.0 CODING 



3.1 LINE_LAYOUTS 

3.1.1 COMPASS_OPER!TION_LINES 

The following list of column numbers reEresent the beginning of each 
field in a COMPASS ceding line. (An exception is allowed for macro 
definitions in system texts where space is critical. Refer to 
section 3.6.5.) 

Column 1 = Continuation field (cemma) if required 

Column 2 = Location field 

Column 11 = Operation field 

Column 18 = Address field 

Column 30 = Comment field 

Column 73-80 = Reserved 

If a field is full or overflows intc an adjacent field, then two 
spaces should separate the fields. For readability, a block of 
comments can be aligned in a column past column 30. Column 72 of 
the comment field should be blank unless a continuation line is 
required. 

3.1.2 COM P A.g S_CC H ME N I_I I N E S 

The following list of column numbers represent the format of a 
comment line. A full description of where and how to use comment 
lines is found in section 2. 

always contains an asterisk 

(see section 2.2.3) 

generally blank 

contains the text of the comment 

reserved 

3.2 „_____ 

The following sections define the components of a program in the 
order they appear within the program. It is not expected or 
required that every program will consist of all components 
described. In this discussion a "program" is a relocatable program 
unit (from "IDEM" tc "END"), an entire absolute program or a common 
deck. A subroutine is a routine within a program. 



Column 


1 


Column 


2-5 


Column 


6-10 = 


Column 


11-71 = 


Column 


72-80 = 


PROGRAM 


LAYOUT 
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3.2.1 GEOUP_l_INSTEUCTIONS 

Group 1 instructions appear at the beginning of each program and 
contain the identification and environment information for the 
program. The following examples define the layout of the Group 1 
instructions for each type of program. 



3.2.1.1 PEE IPHERAL_PRCCESSOR_PECGE AMS 

1 11 .18 -30_ (Columns) 

IDEM XXX, ORIGIN 
MACHINE (optional) 

PEEIPH 

NQLABEL (deadstart routines) 

BASE M 

LIST (optional) 

SST 

TITLE XXX - program description. 
♦COMMENT deckname - description. 

COMMENT COPYRIGHT CCNTRCI DATA CORPORATION, year. 
XXX SPACE 4,10 



3.2.1.2 CENTRAL PRCCESSOR PROGRAMS 



IEENT XXXXXXX,EK£ program description 
ABS (optional) 

MACHINE (optional) 

LCC (optional) 

SST (optional) 

ENTRY YYYY (optional) 
SYSCCM B1 ' 

LIST (optional) 

TITLE XXXXXXX - program description. 
♦COMMENT deckname - description." 

COMMENT COPYRIGHT CCNTRCI DATA CORPORATION, year. 
XXX SPACE <!,10 
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3.2.1.3 COKMON_DEC]ls 

1 11 18 3G (Columns) 

+ + + + 

CTEXT XXXXXXX - common deck description. 

SPACE 4,10 
QUAL$ IF -DEF,QUAL$ 

QUA! XXXXXXX 
QUAL$ ENEIF 

BASE . B (B = any legal value) 

CODE C (optional) ' 

* COMMENT COPYRIGHT CONTROL DATA CORPORATION, year. 

XXX SPACE 4,10 

Refer to section 4.4.3 for further information on qualification of 
common decks. 



3.2.2 PBOGR AM_LEVEL_DOCUKENI AT ION 

Program level documentation consists of overview, external and 
internal documentation as described in section 2.3. 



3.2.3 MACRO DEFINITIONS . 

The macros are in alphabetical crder. C cm men decks which define 
macros should be included before local nacre definitions in 
alphabetical order. 



3.2.4 IISTAILATICN_SIMECL_CEFINITTCKf 

Installation symbols are parameters that may be changed by a site 
when installing a product. These symbols iray include buffer 
lengths, default values, and timing delays. Installation symbols 
are defined in alphabetical crder unless functional order is more 
meaningful. The installation syirbcl definition area shculd be 
bracketed by internal bracket lines (***•*). 



3.2.5 LOCAL_SYMECL_DEFINITICNS 

Local symbols are parameters that shculd net be changed by an 
installation. These symbols may include cede generation symbols 
(QUAL$, DBI$, etc.) And symbcls used fcr cress reference purposes. 
Local symbols are defined in alphabetical crder, unless 
functional crder is more meaningful. 
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3.2.6 GLOB A L_ME EC BjT EEF IN IT ICNS 

This section of the program is used to define memory that is preset 
with data. This section may include FEls, tables, and working 
storage. Global memory definitions are defined in alphabetical 
order unless functional order is mere meaningful. 



3.2.7 MAIN-LOOP 

This section of the program contains the major logic "and control 
flew for the program and internal documentation for that flew (see 
section 2.4). A TITLE line with an appropriate subtitle precedes 
the first primary surrputine. 

3.2.8 PRIMAEY_SUBRCUTINES 

This section of the program contains the sufcroutines which are of 
major importance to the program. They should be in alphabetical 
order unless there is a logically associated set of subroutines 
which interact together (in which case these subroutines may be 
grouped together). Each subroutine contains documentation as 
described in section 2.4. A TITLE line with an appropriate subtitle 
precedes the first primary subroutine. 

3.2.9 SEC N D A R Y_ SjU E R C U T INE S 

This section of the program contains subroutines of miner importance 
to the program. They should be in alphabetical order unless there 
is a logically associated set of sulroutines which interact together 
(in which case these subroutines may be grouped together). A TITLE 
line with an'apprcpriate subtitle precedes the first secondary 
subroutine. Each subroutine contains documentation as described in 
section 2.4. 

Common decks (except those used for initialization) are after the 
secondary subroutines. Common decks should te listed in 
alphabetical order whenever ccssitle. 

3.2.10 WQRKII£_STCRAGE_ANS_2HEEIRS 

This section of the program contains working storage and buffer 
definitions that are not preset with data. (Refer to section 3.4.5) 
Use of EQU or ESSK is preferred tc ESS since additional cede is not 
added to the binary. 

3.2.11 INITIALIZATI0N_C0DE 

Code which may be overlayed after program initialization is included 
here. 
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3.2.12 PBCGRAH_TEEKI NAJICN 

All programs end with an "ENE" statement except commcn decks which 
end as follows: 

1 11 18 30 (columns) 

+ + + + 

BASE * (if applicable) 

CODE * (if applicable) 

QUAL$ IF . -DEF,QUAL$ 

QUA! * 

YYY ECU /XXXXXXX/YYY (unqualified entry point) 



QUAL$ ENEIF - 
XXX ENDX 

If "CODE x M is used at the beginning but "CCDE *" is net used at the 
end of a common deck, it must be explicitly documented in the common 
deck header. 

If the main listing title has been changed by use of an IDENT or TT1 
line, the main title must be restored with a TTL card just before 
the END line ..tc provide the correct title en the symbolic reference 
table. 



3 . 3 I NSTRU C TI0I_ I S E X _EC EE AT^_ AS E_P AE AM ET E BS 
3.3.1 M£ISTEE_USE_AND_SPECIF1CATICN 

3.3.1.1 B0_REGIS1EF_USE 

The E0 register shculd net be specified in instructions which test B 
registers. The assembler assumes EC if the requisite number of B 
registers is not specified. 

3.3.1.2 U_REGISTER_USE 

The B1 register must always contain the value one (1). The "SYSCOM 
B1 W macro is included in each program tc indicate that E1 will 
contain this value. B1 must be set to 1 immediately upon program 
entry. B1 is then used by CCKEASS in conjunction with the R= psuedo 
instruction to generate 15 bit instructions rather than 3C bit 
instructions. 
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It should be assumed that calls tc external entry points which may 
be loaded from an external source destroy E1. Therefore, E1 should 
be reset to one after these calls. 



3.3.1.3 PACK_AN2_N2IINAL_SH I FT_X_BEGISTEES 

In the Pack and Nominal Shift instructions, the X register is 
specified before the E register, as follows: 

PXi . Xk,BD 

LXi Xk,Bj 

3 . 3 . 1 . H UN PA CK_ AND_N0 BKA.LI2I_I_ BEG I S. IE E £ 

In the Unpack and Normalize instructions, the B register is 
specified in the opcode field immediately following the opcode. 

UXi,Ej Xk 

NXi,Bj Xk 

3.3.2 IULTIFLE_ICGICAL_TESTS 

When a PP program tests a value in the A-register for equality with 
several possible values, it may be dene with a sequence of logical 
difference (exclusive "or") operations, as fellows: 

LMC AA 

ZJN XYZ12 IF TYPE AA 

LKC BB~AA 

ZJN XYZ24 IF TYPE BE 

LKC CC~BB 

ZJN XYZ36 IF TYPE CC 

The value being tested is specified first in the LKC. ' 

Alternatively, a table look-up may be mere efficient. 

3.3.3 SH I I T_IN STEU CT ICN_P AB AK E T E ES 

Shift counts in shift instructions which are used to test bits, are 
coded in one of the following forms: 

A-B (first shift of a word) 

A-B-AA+EB+K (next shift of the word) 
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Where : 

A = The desired position of a tit in the word. 

B = The original position of a bit in the word (tefore any 

shifts). 
AA,BE= The A and E parameters frcE the previous shift of 

this word . 
M = Modulus value 

Note: The modulus values (6C for CPU and 22B for FP) may have to 
be added to the shift value if the resulting value is not 
within the legal limits for the instruction. 

Example : 

1. To shift bit 47 to bit £9: 

LXi 59-47 

2. To shift the result of example 1 so that bit 32 of the original 
register (before any shifts) is in tit 59 of the result: 

LXi 59-32-59+47 " ' 

3. To shift the result of example 2 so that bit 58 of the original 
register (before any shifts) is in tit 59 of the result: 

LXi 59-58-59+32 

Example: 

1. To shift tit 2 tc bit 21E: 

SKK 21-2 

2. To shift the result of example 1 so that bit 5 of the original 
register (before any shift) is in bit 21 of the result: 

SHS 21-5-21+2+22 

A modulus of 22B is needed in this, case tc avoid executing a right 
shift (ie. The resultant shift would otherwise be negative.) 
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3.3.4 BOOLE A N_MA SK_ U SJ.GE 

The mask created fcr use in tcclean instructions depends en whether 
the field cf hits tc he extracted is in the left or right hand part 
of the word. If the field of n hits is in the left hand part of the 
word, use the following methed: 

MXi n 

BXj Xi*Xk (Xj contains the extracted field) 

If the field of n tits- is in the right hand part of the word, the 
following methed is used: 

MXi -n 

BXj -Xi*Xk (Xj contains the extracted field) 

If the mask is used in more than one way, the first usie determines 
how it is defined. 



3.3.5 EEL A TJ VE_ A E DEEDING 

Relative addressing (such as *+n and *-n, where n is a numeric 
value) should net he used except: 

T. In timing dela~ys (where *-1 is the only acceptable value). 

2. For instruction modification (where *-1 cr *-2 are the only 
acceptable values). 

3. In PP code tc reference tytes within a CPU word. The relative 
address must be in one cf the following forms: 

tag+n 
tag+c*5+n 

where: 



tag = base address 
^ c = CM word within the PP buffer 
n = byte within the CM wcrd (0 - 4) 



3.3.6 JUM£_IISTRJJCTICI_USX ' 

Unconditional juirps in CPU cede are coded using the EQ instruction 
so that the instruction stack is not voided. When it is necessary 
to void the instruction stack the EJ instruction is used. (The EJ 
is the only instruction which vcids the stack on all central 
processors. ) 

PP jump macros MJE, KJP, PJP, UJE, ZJP can be used tc assemble short 
or long jump as needed; however, these macrcs should be avoided when 
branching forward since a leng jump sequence is always generated if 
the jump address has net yet been defined en pass 1 cf the assembly. 
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A blank line is inserted after each unconditional jump instruction 
to indicate a break in the program flow. If the unconditional jump 
occurs at the end of a subroutine, a SPACE line or TITLE line may be 
used . 

A blank line is also required after an implied unconditional jump. 
The following are examples of an implied unconditional jump. 

Example: 

A blank line should be inserted after macro calls that break the 
flow of execution in a sequence of code. 



NZ X1,tag2 IF comment 

ABCRT TERMINATE 



(blank line) 
tag2 SA1 B2 



Example: 

When code occurs before the SUEE, there should be a blank line 
between the code and the SUEE. 

tag2 LDN ' comment' 

(blank line) 
tag SUEE ENTEY/EXIT 



tagl 



UJK tagX RETURN 



tagA ESS 1 comment 



/ 



When storage locations for a subroutine are defined at the end of 
the routine, there should be 2 blank lines between the code and the 
first data tag. 

3.3.7 SUBEOUTINE_ENTgY 

Each subroutine has one and only one entry point. Exceptions are 
allowed as follows: 

If memory limitations in a IF program make this impractical. 

For termination subroutines (such as error processors). Each 
entry point should be documented within the subroutine. 
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PP and CPD subroutines which are entered via a return jump- contain 
the following instruction at their entry/exit point: 

tag SUEE ENTRY/EXIT 

UJN tagX RETUEN 
or, 

tag SUES OTEY/EXIT' " 

*. 

EC tagX EE1URN 



A subroutine may alsc consist cf a block cf code that is entered by 
a jump instruction. In this case, the subroutine entry points 
should be clearly documented using a BSS pseudo-instruction: 

TAG BSS ENTEY 



Subroutines defined, with SUEE shcu."ld be used for hangs and error 
processors so the EJ/RJM for C5/PE cede leaves a trace cf the 
caller, even though return tc the caller is not used. PP's should 
write the caller's address and ether pertinent information in the PP 
output register cr message buffer (space permitting) before issuing 
a HNGM monitor function. 

3.3.8 CPU_CODE_OFTI H IZ ATION 

An effort should be made to avoid the generation of KO-CFs at the 
end of a 60-bit word. This may be dene ty arrangement cf cede so 
that each 60-bit wcrd is completely filled with executable code. 
This is alsc done for instructions which have an optional "k" 
parameter by supplying a zero value for "k", thus generating a 30- 
bit instruction instead of a 15-bit instruction. The way to do this 
is to append a "+" tc the register in the variable field cf 
the instruction, as shown below: 

SA4 A1+ (Generates 3C-bit instruction) 

This indicates that the padding was added for optimization purposes 
and may be removed as necessary when the cede is modified. 
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When initializing an X register tc zero, a 

SXi B0+ 

should he used if a 20 hit instruction packs better. 

If a 15 hit instruction packs better, 

( BXi Xi-Xi i 

is preferred; hut for efficiency 

SXi EO 
MXi 

also may he used interchangeably . 

3.3.9 CLEMING_PF_KEKORY , 

The following ceding seguence is used tc clear 5 consecutive words 
of PP memory to zeroes: 

LDK ZEBL 
CRD tag 

The constant ZER1 should not he assumed tc he at address absolute 
zero in memory. 

3.3.10 INSTRUCT ICN_KCDIFICATICN 

Instruction modification greatly increases the complexity of code 
and is a reliable source of program errcrs. It is a practice to be 
avoided wherever possible. The' sole justification for instruction 
modification is cvervhelming space cr time-critical constraint, such 
as a crowded PP, an In-stack leep, cr a hardware driver. It is 
particularly important that cne routine modifying the contents of 
another routine be avoided. It is far preferable to employ a global 
variable for communications between routines, even at the expense of 
some storage. 

Where a routine irust modify code within ancther routine, the 
modified code must be documented as an EXIT condition from the first 
routine and an ENTRY condition tc the second. 

Data locations iirbedded within a routine and referenced by more than 
one routine should be assigned descriptive, global variable symbols 
(this is an exception to the standard for the naming of data 
locations within a routine). Ihis will somewhat decrease the 
chances of error arising from their use. 
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Instructions which must he modified are tc te followed by a comment 
which shows each alternative form under which the instruction can 
take. The following examples shew the layout used: 



Example : 






tag 

* 

* 
t a g A 


LDC 
LDC 
LDC 

EQU 


TBCO 
TWTO 
TFCN 
*-1 


Example: 






tagA 

* 


LDC 
LDC 
STD 


* 

(TO 

T1 



SET READ FUNCTION 
(WRITE FUNCTION) 
(POSITION FUNCTION) 



RES10RE (TO 
(CONTENTS CF TO 



The comment in ( ) should descrite the conditions under which the 
instruction is changed. 

In CPU code, care must he taken tc insure that the instruction being 
modified is not already in the instruction stack. Since the only 
way to guarantee this for all mainframes is to perform an EJ 
instruction, any CEU program that dees cede modification must have 
at least one RJ instruction letveen the modification and the 
execution of the cede. This EJ may te a call to a dummy subroutine, 
or to a "normal" cne; if a call tc a normal subroutine is also being 
used to void the instruction stack, the comment on the EJ should 
note that fact. 

PP short jump instructions which must be modified are tested for 
range errors. The LCC pseudc-CE is used and the jump instruction is 
actually assembled if the program size is net a critical factor. 
For example : 



TAGA 



TAGB 



LDK 


TAGB 


STM 


TAGA 


* 

KJN 


.TAG1 


UJN 


TAG2 


• 

BSS 





LCC 


TAGA 


UJN- 


TAG2 


LOC 


*0 



IF TIKE NOT EXPIRED 
(ONE CEU ONLY) 



comment 
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When program size is a constraining factor and the tag tc be 
modified is previously defined, the ISTCEE iacro defined in COMPMAC 
should be used: 

ISTCEE CADER, (INSTE) 

where CADEE is the address cf the cede tc te modified, 

INSTE is the instruction (op cede and address field) to be stored. 

For example: 

TAGA KJN TAG1 IF TIKE NCT EXPIRED 
* UJN TAG2 (CM CPU CNIi) 



ISTOEE TAGA, (UJN TAG2) 
Which generates the following sequence cf instructions: 



LDC 


** 


CBG 


*-1 


LOC 


TAGA 


UJN 


TAG2 


IOC 


*C 


STM 


I AG A 



When program size is a constraining factor and the tag to be 
modified has not yet been defined, the jump should be assembled as 
part of an LDC instruction as fcllcws: 

LDC UJNI+TAG2-TAGA 

STM TAGA 

In this case, the EBBNG psuedc instruction trust be used tc test for 
range errors as fcllcws: 

EEENG 37+daddr-jaddr (comment) 
or 

EEENG 37+ jaddr-daddr (comment) 

(depending on whether the jump is a backward or forward jump 
respectively ) 

Where: I 

jaddr =address of jump instruction 
daddr =destination address of jump 

Again, instruction modification should be avoided in PP and CPU code 
whenever possible. 
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3.3.11 COK«CN_DECK_REGISTJER_USAGE 

CPU code within commcn decks avcids using registers AO, A5, XO and 
X5 unless absolutely necessary. If these registers must he used, 
they should he restored before exiting tc the calling routine. 

3.3.12 PP_ ADKx_I£I^_lMK x _LPK jt _§EK_Macr c s_U s ace 

Use of ADK, LDK, LMK , LPK , and SEK macros defined in CCMPHAC are 
encouraged, since the actual instruction assembled will be adjusted 
to a 0, 1, or 2 byte instruction as" needed ,' depending on the tag 
values in the operand field. If the operand value reduces to zero, 
no instruction will be generated (except for LDK). Operands to 
these macros should not be numerics cnly (usefulness for tags is 
recommended). Because of the variability of the code generated by 
these instructions, this code should not be changed ty in-line code 
modifications. 



3 . 4 DATA USE, FORMAT, AND PARAMETERS 

3.4.1 LITERALS 

Literals may.be used for read-only constants only. Error message 
text should net be defined as literals, hut rather should be defined 
in data statements (preferably in tables). 

3.4.2 D AT A_ FORK A IS 

Data is specified in its natural fern (readable and understandable 
by humans) using post-radix symlcls as required (see section 
3.6.1). If conversion considerations make this impossible, the 
comment field will contain the natural fern; of the data. Octal 
values are not used for character data unless the data cannot be 
specified in any ether way. When the VFD is used, it cannot ' 
generate more than one CM word of data. 

If a data item dees not require an initial value preset at assembly 
time, BSS should be used to reserve space rather than CON. 

Only one piece of data is specified en a line of code unless a block 
of data is being specified for use as a single data item tc be 
referenced by a single name. 
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LOG 





COS 


ENK 


CON 


ACF 



CON 


VSN 


LOC 


*C 


EQU 


*-TFCN 



NOS COMPASS 4/26/83 

3.4.3 TAEiE_£ENEEATICN 

Tables which are generated with entry ordinals relative tc the base 
address of the table, should use the LOC pseudo-cp as shewn in the 
following example: 

TFCN ESS table entry 

first entry 
second entry 



last entry 

TFCNL EQU *-TFCN table length (optional) 

Where tables are described, they are defined so they can be 
processed by the "Eocumentation Table Generator". A description of 
this format is fcund in the external documentation fcr the program 
DOCMENT. 

3.4.4 DIRECT_CELL_USE 

Direct cells .are defined using one cf the following methods: 

1. A single cell: 

xx EQD n description 

2. Multiple cells: 

xx EQU n - m description 

3. Contiguous cells: 



description 
description 



zz BSS - 1 description 

ICC *0 





LOC 


n 


XX 


BSS 


1 


yy 


BSS 


5 
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4. Contiguous direct cells cr ether sequential tag definitions 
without reserving space: 



BEGIN 


BSSN 


n 




XX 


BSSN 


1 • 


description 


yy 


BSSN 


5 


description 



zz BSSN 2 description 

END , BSSN 

The BSSN macro is defined ir CCMCMAC and COMPKAC. 

Where: 

xx, yy, zz = the tag for the cell 

n = location of the cell (cr first cell) 
m = location of the last cell 

Multiple definitions of direct cells should re avoided. 

The first few direct cells in the PP should not be used for data 
which is critical to debugging. The deadstart dump process 
destroys the contents of these locations: 

TO - T3 and 7774- - 7777 

3.4.5 BUFFEE^DEFINITIONS 

Large buffers and working storage areas should be defined using EQU 
statements (rather than BSS and ESSZ) tc avoid unneccessary loading 
of the buffer areas that do net require initialization. Ihis 
applies to CPU and PP code. 



IEUF 
OBUF 
EFL= 

Small buffers and working storage areas may fce allocated via BSSZ, 
if the program requires that the area be zero on program initiation, 

The BSSN macro defined in CCKCMAC and CCEPKAC may also be used to 
define buffers. N 



USE 


BUFFERS 


ECU 


* 


EQU 


IEUF+IBUFL 


EQU 


CEUF+OEUFL 



3 . 5 DAT A/CODE_N AKIN G_ TEE KIN C IC GJ 
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3.5.1 USE_CF_CCNE I1ICN_TESM INOLCGY 

The following terms are used tc describe the condition of tits used 
as flags or switches. The selected terms should be used 
consistently within a program. 



1 







on 


off 




true 


false 




set 


clear 


(reset) 


nonzero 


zerc 




up 


down 





3.5.2 1 AGS_ WITHIN_SUBR CUTINE S 

Each subroutine (main loop, primary subroutine or secondary 
subroutine) has a ireaningful three character name which is derived 
from the title of the subroutine (see section 2.4). 

Tags used for branch instructions are of the form: 

XXXn Example: GFN1 

Tags on code which is added later tc the subroutine are of the 
form: 

XXXN.n Example: GFN1.1 

Tags that are inserted between the SUBR and the tag XXX1 by 
corrective cede are cf the form: 

XXXO.n Example: GFN0.1 

Tags on storage locations (constants, tempcrary storage and 
instruction modification) within a subroutine are of the form: 

XXXa 

Where: 

XXX = Subroutine name 

XXXN = Tag- preceding an added one 

n = Number from 1 tc 99 (in consecutive order beginning at 

the entry point and ending at the exit point) 
a = Letter from R tc Z and AA to ZZ (in alphabetical order 

and excluding X) 

Tags of the form XXXn, XXXn.n, and XXXa shculd not be referenced 
outside of subroutine XXX. 
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If the above rules cannot be followed due tc tag unavailability, 
the fenfire subroutine will have its tags resequenced. 

Tags on storage locations within a subroutine which must be 
referenced outside of the sufcrcutine should ie given appropriate 
global tags. v 

3.5.3 TAGS CN DATA 

3.5.3.1 DIRECT_CELIS" 

All PP direct cells have twc-character names. 

The following table defines the preassigned direct cell usage: 

'Contents Kame Location 

Control Point BA/100 EA 55 

Control Point FL/100 FI 56 

1 CK 70 

100 - HH ■■" 71 

1000 TH 72 

3 TE 73 

CPA address .. CP. 7«i 

PP input register address IA 75 

PP output register address CA 76 

PP message buffer address EA 77 

3.5.3.2 CCDE_CONT£CL_NAKES 

Names used for assemtly options, micros and to control cede 
generation are five cr more characters long. 

3.5.3.3 TABLE_NAME£ 

Tags used on tables have the form: 

Txxx 
Tags used for talle lengths have the form: 

TxxxL 
Tags used for tatle entry lengths have the form: 

TxxxE 
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Where: 

xxx = 3 character table name 



3.5.3.4 GLOBAL_KIHC|Y_LgCATICNS 

Names used for global memory locations (locations referenced by more 
than one subroutine) are four characters long. Multiple definitions 
for global memory locations shculd be avoided. 

3.5.4 CONSTANTS USED AS INSTRUCTICNS 

Four letter tag names should end in "I" if the tag name is defining 
an instruction. 

For example: 

LJHI ECU 0100B *LJM* INSTRUCTION 
SHBI EQU 1000B *SHN* INSTRUCTION 

FP instructions are defined as constants in common deck CCMSPTH. 



3.5.5 I F/ELSE/E N E IF_S. YKBO LS 

Symbols used on IF, ELSE, ENDIF and SKIP psuedo instructions may be 
system symbols or local symbols cf the fcrm: 

.a 

where: 

a = letter from A to Z 

Unlabeled, unnumrered IF/ELSE/SKIP/INDIE sequences should not be 
used as they may unexpectedly affect ether sequences. For very 
short sequences a line count may be used, fcr longer sequences 
labels are preferred. 

3.5.6 NON-LOCAL_NACRC_SYKBOIS 

To avoid conflicts with user cede, ncn-lccal symbols defined within 
macros are cf the fcrm: 



where: 

n = number from 1 tc 99 
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3.5.7 LOW_CCEE_LCCA TICN_S YME C IS 

Symbols that are used to define locations in low core (CHE) are of 
the form: 

xxxL 



3.5.8 C0NU0L_E0INl_iR£ft_L0CiTICH_£YKB01£ 

Symbols that are used for defining locations in the control point 
area are of the fcrm: 

xxxW 



3.5.9 MONITOR FUNCTION ..SYMBOLS " 

Symbols used for monitor function requests are of the fcrm: 
xxxM 

3.5.10 SEGATIIE_FIELE_IENGTH_^IKECIS 

Symbols used tc reference .data in negative field length are of the 
form: 

xxxN 

3 . 6 PSEUDO_INSTRUCTICN_USE x _FORM AT^_AND_FA E AMETERS 

3.6.1 BASE_AND_ICST_EADIX_USE 

The BASE DECIMAL pseudo-op is used in all CPU code. The BASE MIXED 
pseudo-op is used in all PP cede. Ecst Radix is allowed fcr data 
formats other than octal and decimal; in specifying timing loops 
where decimal values are more meaningful tc humans; and where 
external specifications such as ANSI or corporate standards dictate 
the use of a particular format. 

3.6.2 EXTERNAL REFERENCES 

The EXT pseudo-op is not used. All references tc external names use 
the form =Xname. In an absolute assembly, references tc locations 
in other overlays use the form =Xname. 
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3.6.3 S PA CE_C AE D_ F C R K A T 

The format cf the SPACE pseudc instruction is: 

tag SPACE 4,n 
where: 

tag =table, nacre or subroutine name 
n =stateient count 

The statement count is a multiple of 5." that" is greater or equal to 
10. It should be large enough tc avoid breaking documentation 
across page boundaries. 

3.6.4 CONDITION AI_C0EE 

Numeric skip counts are discouraged with IF, IFC, ELSE, etc., 
because this makes cede difficult tc read (especially when the 
skipped lines are not listed). ENDIF shculd be used instead. An 
exception is allowed for very short sequences and for systems texts 
where space is critical. 

Conditional sequences should be bracketed with labels (refer to 
section 3.5.5) which allows their, tc he easily spotted and matched in 
listings. 

When either end cf a sequence of conditional code occurs at a break 
in the listing (SPACE, TITLE, or Hank lines), the spacing lines 
shculd be placed sc that spacing will be correct whether the test is 
true or false. Usually this means moving the spacing outside the 
conditional code. \ 

Example: 



EQ - TAG1 CONTINUE 

(blank line) (outside conditional cede) 

EK"*SCCPE* 

BEAE CCKHANE 

RETURN 

CCMKANE BUFFER 

READ CCKMAND 
RETURN 

(outside conditional code) 
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.A 


IFC EQ,*"SY 


TAG3 


CCNIFCI 1AGA,R 




EQ TAGX 




(blank line) 


TAGA 


BSS 8 


.A 


ELSE 


TAG3 


CONTROL CCDR 




EQ TAGX 


.A 


ENDIF 


a be 


SPACE 4,10 
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3.6.5 MAC ECS 

Macro definitions shculd include a description of hew the macro is 
called and a description of all formal parameters. (Eefer to 
section 2.5.) 

The PUEGMAC psuedc instruction shculd te used to disable any 
previous macro definitions of the same name. 

Non-local symbol definitions shculd te of the form .n (see section 
3.5.6). ... 

To avoid terminating multiple macro definitions, the ENDM 
instruction should he labeled with the macro name. 

The MACEEF macro (defined in SiSIEXT) may be included within the 
macro definition body to provide symbolic reference table listing of 
the calls of the macro. 

The SYSTEM XXX, = macro (defined in CFCCK) shculd be used for cross 
referencing of CI programs calling FF programs without a standard 
interface (Examples: CPUMTE calling 1MA, MAGNET calling 1HT via SPC 
call). 

The EXECUTE XXX, = macro (defined in CCMFKAC) should be used for 
cross referencing cf PP programs calling FF programs or overlays 
without a standard interface. 

When space is critical, as in systems texts, the following list of 
column numbers represent the beginning cf each field in a COMPASS 
coding line to be used in a iracrc definition. 

Column 2 = location field 

column 3 = operation field 

column 6 = address field 

column 73 = reserved 

If a field' is full or overflows into an adjacent field, then one 
space should separate the fields. If comments are required, they 
should appear as stand-alone comments rather than embedded comments. 

3.6.6 I>IS_F SEUE0_ I K S TEU CTIC H 

The DIS pseudo instruction shculd net be used to generate data since 
the syntax cf the instruction determines the format cf the data. 
The DATA psuedo instruction should be used instead. 
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3.7 TESTS_FOE_C^EEFLCW 

CPU and PP programs should contain assembly checks for certain types 
of overflow conditions. The following points should be considered 
when making the checks. 

PP programs and overlays are generated by COMPASS in multiples 
of 5 PP bytes (1 CM, word). Therefore, when reading an overlay 
from central memory to FP memory, mere FP bytes may be destroyed 
than the actual number of bytes of FF cede. 

Overlays loaded from mass storage 'tc FF' memory come in 
multiplies of 500 PF bytes. At least 5 bytes of the last PEU 
are required tc represent end of record which can increase the 
size of the overlay by one FEU (500 bytes). 

Care should be taken to insure that the literals block has been 
defined before checking for the overflew conditions. literals 
can be flushed by specifying: 

USE (name) 

USE . * 



The OVERFLOW macro (defined in CCMPMAC) may be used to perform these 
checks. 



3.7.1 CM LOADS 

All PP programs include a test fcr the amount of cere remaining 
after a CM load as shown in the fcllcwing example: 

USE CVERFLCK 
xxx BSS 

EBENG 7772-xxx FP MEMCFY OVERFLOW 

Where: 

xxx =tag for the last lecatien defined 

3.7.2 TAELE_OVERFICJ 

If a PP program uses more storage than it declares, its length is 
checked as shown in the following example: 

USE OVERFLOW 

xxx BSS 

xxxE ECU xxx+xxxl 

E'BBHG 7777-xxxE FRCGRA8 CVEEFLOW 
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Where : 



xxx = tag for the last Iccaticn defined 
xxxL = length cf undeclared space 
xxxE = end of space used 



3.7.3 MASS_STCEAGE_LCADS 

A test will he included in each PP program which may reside on mass 
storage. This test will protect against a load which exceeds the 
end of memory in the PP causing wrap around. The "OVERFICW" macro' 
is available in CCKPHAC for this operation. 



3.7.4 OVEELAY_LCADS 

Programs calling overlays should test fcr memory overflew with the 
following test : 

ERRNG (lwa+1 )-(lcad addr)-len comment 
where: 

1wa+1 = first byte net to he destroyed by the zero level 

overlay 
load addr = address where the overlay is loaded 
len _ = length. of overlay > 

The length of an overlay is defined to be the number of bytes 
destroyed by the overlay during leading and execution. The overlay 
should also contain a test to insure that it does not exceed its 
defined length. The overlay length can he adjusted to a higher or 
smaller value as leng as none cf the tests fail. The "OVERFLOW" 
macro is available in COKPMAC fcr this operation. 



3.8 EELOCATMIEJCPU_CODE 

The first word of a relocatable CPU program should be of the format 

42/OLDECK, 18/ADDR 

where: 

DECK = deck name J 

ADDR - entry address cf prcgran 

This word is used to locate the first wcrd address and entry point 
of a routine in a CK dump. 

The contents of £0 must never be used in a library level routine 
unless it is saved and restored. AC is used by FTN as a base 
register for formal parameters in subroutine linkages. 
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3 . 9 ROUTINE/SDE BC UTI RE_CO|5EL EX II Y 

In this context, the term "complexity" is used in its formal sense; 
that is, a sense of the structural incoherence (entropy) cf a 
routine. The more complex a routine is, the more liable it is to be 
a source of errors, difficult tc implement, and worse to modify or 
correct. There are no hard and fast rules for gauging the 
complexity of a routine, but it can be said in general that the 
longer it is., the more decisions it makes (branches), and the more 
functions it performs, the mere complex and unreliable it tends to 
be . 

In order to reduce complexity, the following guidelines are to be 
followed whenever possible (i.e., net impossible) . 

1. One routine - one function. Each routine should have one 
clearly defined function. ' 

2. 10-Tag rule. If there are mcre-than 10 branching locations 
within a routine, it is most likely attempting to perform 
too many functions (see 1 above). It should be considered a 
candidate to be broken up into functional units. 

3. Code Modification. Minimize within routines, avoid between 
routines. If used retweeh routines, document thoroughly. 

4. Hidden Variables. Data placed in a register with the hope 
of being used at some later time often may net survive to 
its destination. Consider global variables for 
inter-routine communication, especially when there are one 
or more routines intervening. In any case, all exit 

, conditions from a routine must re documented. 

5. -Code for the Future. Always consider the implications of 

debugging, modification, and maintenance; structure code to 
make these tasks easier. 

i 

4.0 MISCELLANEOUS 



4 . 1 PROGRAM.. NAMING 

4.1.1 L ENG T H_C F_ I R C G S A M_N A M E 

Peripheral processor program names are 2 characters long. 

Central Processor program najres are 4 tc 7 characters long, 
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4.1.2 BESEBVED_NAKES 

The following PP program names are reserved cr presently defined for 
use (x means any character legal in a PF program name and n means 
any number between 0-9): 

Uxx Reserved for installations 

nllx Reserved fcr installations 

9AA-9T9 Reserved fcr system use 

9VA-9Z9 Reserved fcr system use 

9GA-929 Reserved fcr diagnostics 

93A-939 Reserved fcr system use 

The following names are currently used by NCS: 

6xx Callable mass storage drivers 

7xx Kass storage error processing overlays 

9AA-9D9 DSD overlays 

9EA-9F9 DIS overlays 

9GA-9G9 C26 'overlays 

Oxx location free overlays 

OCx Contrclrfare identif ica ticn processors 

OPx Rack number identif icaticn processors 

OTx Automatic track flaw processors 

UxxL PPCOM symbol - reserved fcr installations 

Ux'xM PPCOM symfccl - reserved fcr installations 

UxxN PPCOM symbol - reserved fcr installations 

UxxP PPCOM symbol - reserved fcr installations 

UxxW PPCOM symbol - reserved fcr installations 

In general, tags beginning with U should net be used as tags in 
NOSTEXT, CCMSXXX decks, etc. or as macro names in COMCMAC, COMPKAC, 
etc. These tags should' be reserved for installation use. 



4.1.3 C0KM0N_DECK_|iAM.F,S. 

Common deck names are seven characters in length and in the 
following form: 

COMxaaa 
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where : 

aaa = Th€ name of th€ routine cr a symbolic name if no 

routine name. 
X = One cf the following common deck indicators: 

C = CPU cede 

F = PP cede 

S = Subsystem text symbols, constants etc. 

D = Display driver cede 

T = tables ( 

M = Mass storage error equivalents 

B' = Data manager"' 

K = Transaction subsystem 

I = Initialisation 

The following indicators are reserved fcr SIMPL common decks: A, E, 
U, Z. 



4.2 CODE_TRANSMITTAL_BULES 

Code which is tc be integrated intc a system build fcr eventual 
release to the field is identified - and formatted as described in 
this section. 



4.2.1 GENEMI-MIES 

Each external ESF .leing answered has a ccrresponding corrective code 
identifier (to be described later). Corrective code answering other 
PSEs is not included in the modification under this identifier. 
Exceptions are allowed where required by interrelated modifications 
for several PSRs. 

Corrections are placed in ascending numerical order; i. e., the 
corrections are sorted in the same order that the lines being 
corrected appear on the program library. If a single modification 
changes several decks, then the ccrrecticns are also sorted in the 
order that the decks appear en the program library. 

Corrections modifying lines with previously modified seguence " 
numbers include the line number cf the nearest preceding original 
line in parenthesis in the comments field cf the modify directive. 

4.2.2 MODSET FORMAT 
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4.2.2.1 MODSET_IDENTIFIEE 

Separate modset name lists are maintained fcr NOS 1 (R5.5) and NOS 2 
(R6.0). Processes fcr naming mcdsets are identical, except for 
multiple deck mcdsets (NSIxxx and NS2xxx), dccumentaticn mcdsets 
(DOKIxxx and DCK2x'xx), and release feature mcdsets (FNIxxx and 
FN2xxx). A modset named 1CD4 in NCS 1, fcr example, has no 
relationship to modset 1CD4 in NCS2. 

You should not sign up for a modset name until after code has been 
generated and tested, and depending en the size cf the medset, even 
after code review has taken place. "This allows other analysts 
submitting code to get the next available iredset name. Ycu should 
not request modset names for mcdsets not tc te included in the 
current series of builds; ycu shculd net request feature modset 
names for a future release until feature code for the current 
release is complete. If you sign up for s a medset name and don't use 
it, notify Code Control so that the modset name can be used by 
someone else. 

The modset name consists of three tc five alphanumeric characters 
which are extracted from the deck name fcllcwed by a 1 to 3 digit 
sequence number. The modset name cannot exceed 7 characters. 

1. For common decks that begin with "CCK" use the last fcur 

characters of the name (example - CEAC4 is a modset in deck 
COKCMAC). 

-2. For PP programs use the three character program name (example - 
CPH2 is a modset in deck CEK). 

3. All other decks use the first five characters of the deck name; 
if the deck name is less than six characters use the entire deck 
name (example - 1IBED2 is a medset in deck LIBEDIT ) . 

4. Modif icatiens which involve multiple decks are given the modset 
name : 

NSIxxx if NCS 1, 
NS2xxx if KCS 2. 

Example - NS1001 is a multiple deck medset in NOS 1. 
NS2C01 is a multiple deck medset in NOS 2. 

5. Modif icatiens which only correct dccumentaticn within a deck are 
gathered together for each corrective code release and given the 
modset name: 

DOKIxxx if NCS 1, 
D0K2xxx if NCS 2. 

• 

Example - DCK1006 is a NCS 1 medset. 
DCK2G06 is a NCS 2 medset. 
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This does not include lines cf cede which have documentation 
changes in them. 

6. If a modset is adding a new feature, the feature modset name for 
each deck modified is obtained from KCS Code Control. 

7. Upon release cf the system, a "composite" modset is generated 
from all feature cede which is tc fce released. 

.4.2.2.2 IODSET_CCREECTION_LETTEE 

When a modset is correcting a previous medset, one alphabetic 
character (starting with A) will he appended to the sequence 
number. Whenever a modset correction letter of "B" or above is 
required, the comments header of the modset must indicate which 
previous modset is being corrected. 

4.2.2.3 OVERFLOW 

Whenever a modset identifier using the abeve conventions exceeds 
seven characters, truncate the last character(s) of the deck name to 
reduce the identifier to seven characters. 

4.2.2.4 IODSET_EXMPIE 

The following format is used for corrective code medsets: 

1 11 18 30 (column numbers) 

+ + + + 

ident 

*IDENT ident initials. yy/mm/dd. 

* / * * * * system. 

*/ **** psR number. 

*/ **** REQUIRES - medset. 

*/ ***** PROBLEM - problem description. 

*/ (continuation of problem description). 

*/ 

*/ SOLUTION - solution description. 

*/ 

*/ ***** RESUBMITS! - yy/mm/dd. 

*/ Reason fcr resubmittal. 

♦DECK deckname 

*I, sequence number 

*D, sequence number 

*D,modname. sequence number (nearest original seq. no.) 

*EDIT deckname (if common deck) 

*/ END CF HCDSET. 
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Where: 

ident = Modset name. 

initials = Initials cf the analyst(s) who wrote' and/or 

tested the cede. Example - ABC. (cne 
analyst) AEC/ADD. (two analysts) 

yy/mm/dd = Date of last medset change. 

system = Name of system in which the modset will be 

released, (ie~ - NCS 1 OS. Or SOS 2 OS.) 

PSR number = This line must always be present. If more 

than one FSE is answered, list the FSB 
numbers en separate lines. If no FSE is 
involved, use the phrase: NC PEE. 

modset = The EEQUIEES lines must always ie present. 

If mere than one medset is required (direct 
or indirect dependency), list the medsets on 
separate lines. If no dependency is 
involved, use the phrase: NONE. 

Since mods to mods in the same release are not allowed for PSE code 
(physically dependent code must be in the same modset), the EEQUIEES 
should specify medsets with logical cr space dependencies. Modsets 
previously released in a standard system usually should not be 
included. For initial transmittal cf feature code, EEQUIEES - NONE 
should be used. Fcr feature repair code, the REQUIRES should 
specify those modsets going intc the same build that are dependent 
on each other. 

The problem description should describe the problem teing fixed by 
the modset and the impact the problem has on the user. The solution 
description should describe hew the problem was fixed. External 
interface changes caused by the installation of the modset should 
also be documented. The problem/soluticn description may be 
combined into cne paragraph to avoid redundancy. 

The *READP1 directive is not used. 



4.3 INTERFACE CONSIDERATIONS 
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4.3.1 S YSTE M_SUPF LIED_I NTEE F ACE S 

All interactions between programs (CPU and FP) and the system use 
system-supplied macros, linkage labels cr common decks. In PP 
programs the system defined direct cells are only used as defined by 
the system. (see section 3.5.3.1) 

4.3.2 PA£AIJlEF_VALirATION 

Each parameter passed between programs will be validated cr 
processed in a way that protects the program from uncontrolled 
actions caused by unexpected values.' 

4.3.3 MEKCRI_ACCESS 

PP programs which access the field length cf a jcb will insure that 
no combination of parameters, errors, etc. will cause access to an 
address outside cf that field length. Addresses should be validated 
prior to using them for a CK read or write to avoid referencing 
areas of memory outside of the control points field length. 

A FP program accessing the field length cf a control point should 
insure the relative address does net exceed 277777B. 

4.3.4 SECURITY 

Programs that perform privileged functions must insure that the 
requester of the function has been given permission by the system to 
use the function. This also applies to the use of special device 
drivers, which cculd be called accidentally cr maliciously by 
unauthorized users. Where common decks are available tc check 
security or privileges, they should be used rather than locally 
written code. 

4.3.5 RESESVATICNS_AKD_INTEEICCKi 

Reservations and interlocks are only used as defined by the system 
and are released as scon as possible. Non-essential cede is not 
executed while a reservation cr interlock is in effect. 

In cases where a reservation reject could cccur, the program will: 

1. Control the rate of reservation re-issue. 

2. Detect and respond tc error conditions. 

3. Protect against storage move lockup. 
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Programs which use reservations and interlocks will insure that the 
conditions are released no matter what program path is taken. 

When multiple interlocks are required, all programs in the operating 
system must request the interlocks in the same order. When a reject 
occurs when attempting to obtain such interlocks, all reservations 
held must be released and the entire sequence of interlocking must 
begin again . 

Care must be taken to not issue da;?file messages, load overlays, or 
pause with non-dedicated channel(s.)_ reserved. 

A PP program must not have a disk channel reserved when it attempts 
to do an' STEM or AFA8 monitor function. If necessary, a ENDMS 
should be performed to ensure this,. 

4.3.6 DOCUKENTIIiG_liAPDWARE_DEFICIEKCIES 

Instructions which are included to compensate for hardware 
deficiencies are documented with a brief description or 
identification of the deficiency. 

4.3.7 NE W_F UNC T I C N/ 1 C W_C C RE_ I D EMIE I E R S 

New tags in PPCOH , use of previously reserved fields in CKB and CPA, 
new PP function numbers, new monitor function numbers, etc. must be 
signed up for via the DSO (Design Support Office). 

4.3.8 DECK_INTEECEFENDENCIES 

Eeware of deck interdependencies which iray require additional 
code/modsets, such as FPCOM and CCKSXXX changes affecting DSDI, DIS 
changes that should also be made in XIS , and COHCXXX/COKDXXX/COMPXXX/ 
COMSXXX/COKTXXX, etc. changes causing CAI1CE u/CALLDIS/CAIIPFU/ 
CA11SYS/CAILTAE, etc. to not assemble without lots of errors. 

4,4 lODULAEITY 

4.4.1 PP_0 VEEL A JS. 

PP Programs use overlays whenever possible to improve the long range 
performance of the system. Overlays are used for any seldom 
executed code such as error handling and seldom used features. 
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4.4.2 HELPERJPP-S 

Helper PPs are net used unless nc ether method exists. The 
availability of PPs when needed should be considered, since the use 
of helper PP's may leatl to deadlocks if nc PP's are available. 

4.4.3 COMMON DECKS 

A common deck containing executable code consists of one cr more 
subroutines (as defined in sections 3.2.6 and 3.2.7) and any 
associated data storage areas. The" purpose' of common decks is to 
increase efficiency in writing cede, insure uniformity cf cede and 
decrease debugging time. Common decks ccntain optimized cede and 
external interfaces that are generalized tc facilitate their use in 
future programs. These decks should be used in preference to local 
code whenever possible. 

Common Decks which ccntain only macros are not qualified. "S" type 
common decks are not qualified by the QUA! pseudo-op within the 
common deck. If an "S" type common deck is qualified externally/ 
the qualifier is the three character name cf the routine. For 
example: 

CCMSaaa (where aaa is the qualifier) 

*-5 DAYFX£g_KESSAGE2 

Dayfile messages issued to the user cr system Dayfile begin with a 
blank character and end with a period. Dayfile messages should not 
exceed 50 characters. Abbreviations shculd be avoided when possible 
in dayfile messages. 

Informative messages should re issued tc the user dayfile only 
(option 3 on the MESSAGE macrc cr the CICK 'option on the call to 
DFM). Messages that indicate that the job will abort are the only 
informative user messages that shculd also be issued to the System 
Dayfile. Special system programs (SCEVAL, ISF, Subsystems, PF or 
Oueue Utilities, etc.) are exceptions and may issue informative 
messages to the System Dayfile when necessary. 
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a. 6 UNHAN£fiBLE_CHANKEL_CCDE 

To avoid channel hangs, bit 2**5 is set en seme PP channel 
instructions. This should only he used when undesirable side 
affects will net result and where it is possible to take corrective 
action. (For example: disconnecting an inactive channel will not 
result in undesirable effects.) Bit 2**5 should not be used when 
unpredictable results may occur. Bit 2**5 is not used with channel 
15. 



Example 



tagl 



IJK 


tagi,CH 


DCN 


CH+40 


RJH 


ERP 



IF CHANNEL DISCONNECTED 
DISCONNECT CHANNEL 
PECCESS ERRCR 



A. 7 SPECIAL ENTRY POINTS 



Special entry points defined by NCS include 



ARG = 
CLE= 
DMP = 
LDR = 
HFL= 
RFL= 
SDM = 
SSJ = 
SSM = 
VAL= 



Inhibit argument processing 

Command line buffer 

Allow special system processing 

Loader processing 

Minimum field length 

Running field length 

Suppress dayfile message 

Special system job 

Secure system memory 

Validation program 



To insure proper leading and execution of special entry point 
programs, special entry points must be declared after normal entry 
points. 



EXAMPLE: 




IDENT 


FWA 


ABS 




ENTRY 


ABC 


ENTRY 


XYZ 


ENTRY 


RFI 


ENTRY 


SSJ 


SYSCOM 


B1 
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4.8 SCEAICH_FILE_NAMES i 

Programs requiring temporary scratch files will use the names 
ZZZZZGO - ZZZZZG9 as names fcr scratch files. Programs which 
require more than these 10 scratch file names must resolve the 
required file names with Systems Design. Such scratch files must 
always be returned at program termination. 
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1 PP E ND I X_A_ Z _ABBR EVICTIONS 

Standard industry abbreviations and programming language names may 
be used even though they are not included in the following, appendix. 

A.1 GENERAL ABBREVIATIONS 

BML binary maintenance leg 

BOI beginning of information 

CLT common library table | 

CM central memory 

CKE central memory extension 

CKM common memory manager 

CMR central memory resident 

CMU cempare/move unit 

CP control point 

CPA control point area address 

CPU central processing unit / 

CS carriage return 

CSU cartridge storage unit 

CW control word 

DAT device access table J 

DIT device interlock table j 

ECS extended core storage 

ESK extended semi conductor iremcry | 

EJT executing job table , * 

EJTC executing job tafcle ordinal 

EM extended memory j 

EOF end of file 

EOI end of information 

EOI end of line 

EOR end of record 

EOS end of stream 

EPD entry point directory 

EST equipment status table . 

FOT family ordinal table 

ETX end of text 

FDX full duplex 

FET file. enviroment table 

FL field length 

FLE field length for extended memory 

FLPP first level PPU 

FKT file name table 

FST file status table 

FWA first word address 

HDX half duplex 

ID identifier or identification 

I/C input/output 

JCB job control block 

JSN jcb sequence name 

LCME large core memory extended 
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logical file name 

last word address 

machine identification; 

multi-mainframe 

machine recovery table 

mass storage 

mass storage adapter 

mass storage table 

mass storage transport (do net use abbreviation where 

cenfusion with Mass Storage Table may result) 

magnetic tape 

multiplexer 

negative field length 

permanent file 

permanent file catalog 

permanent file name 

peripheral library directory 

peripheral prccesscr 

first-level peripheral processor; only on CYBER 176 

(also known as FIEF) \ 

physical record unit 

program status table 

queued file table 

reference address 

reference address for extended memory 

resident central library 

resident peripheral library 

rotating mass storage 

system control point 

status and control register 

single error correction, dcutle error detection 

subcontrol point 

track reservation table 

teletype 

user control point 

unified extended memory for 8X5 

unit descriptor table 

user job name 

volume serial number 



A .2 METKOEK_HOST_PEODUCTS_ABEREVIATICNS 

ABH application block header 

AB1 application block limit 

ABN application block number 

ABT application block type 

ACK block acknowledged 

ACN application connection number 

ACT application character type 

ADB address information 
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LFN 


LWA 


KID 


KEF 


NET 


MS 


MSA 


MST 


MST 


MT 


MUX 


NFL 


PF 


PFC 


PFN 


PLD 


PP 


FPU 


PEU 


PST 


QFT 


EA 


BAE 


ECL 


EPL 


EMS 


SCP 


SCR 


SECDED 


SUBCP 


TET 


TTY 


UCP 


UEM 


UDT 


UJN 


VSK 
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ALN application list nuiter 

CLA ccmirunications line adapter 

IBU input block undeliverable 

IVT interactive virtual terminal 

LCF local configuration file 

LOP local operator 

NAK block not acknowledged 

NCF network configuration file 

NDL network definition language 

NFE no format effectors 

NOP network operator 

NPU network v processing unit" 

PFC primary function code 

SFC secondary function cede 

SM supervisory message 

SHP supervisory message processor 

TA text area t 

TLC text length characters 

TLMAX maximum length of data message block text 

TNAME terminal name 



A. 3 ACEONYMS 



AIP 


BIO 


CDCS 


CBM 


FSE 


IAF 


LCN 


MAG 


MAP 


MCS 


KSF 


MSS 


HAH 


NOS 


NVF 

^ EBF 


EDF 


BHF 


SKF 


SSF 


STM 


TAF 


TIP 


TVF 



Application Interface Program 

Eatchiq . 

CYBER Database Centre! System 

Cyber Becord Manager y 

Full Screen Editor 

Interactive Facility 

Loosely Coupled Ketwcrk 

Magnet 

Matrix Array Prccessor 

Message Control System 

MasE Storage Facility 

Mass Storage Subsystem 

Network Access Method 

Network Operating System 

Network Validation Facility 

Remote Eatch Facility 

Remote Diagnostic Facility 

Eemcte Host Facility 

Screen Management Facility 

Scope Station Facility 

Stipulator 

Transaction Facility 

Terminal Interface Program 

Terminal Verification Facility 
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MIENDIX_B_r_ERE£I_IESSAGE_GUIEE LIKES. 

The following genera 1 ! principles are to he cbserved in designing 
future error messages for NCS. Existing messages should be improved 
as opportunities arise. These guidelines will be formali2ed in a 
later Usability Design Direction Document.^ 

1. The purpose cf an error message is tc inform the user how to 
correct a prcbleir. 

Discussion: It helps tc view error messages as prompts: not 
"this is what you did wrong" tut "this Is how to do it right." 
Messages should be phrased positively. The words "ILLEGAL", 
"INVALID", and "SYNTAX" are specifically not permitted in SOS 
messages. Cf course, there are ether ways to phrase unhelpful, 
negative messages; but these three words are singled cut for 
extinction for being so frequently seen in the company of 
usability offenders. 

2. A single message should diagnose a single error. 

Discussion: For example, if the meaning of message is "more 
than seven characters or leading non-alphabetic character or 
null identifier" it should be three messages. Usually, the code 
must make three separate tests, so it is easy to be precise. An 
exception is when a common deck returns an error status which 
could have resulted from several different conditions. 

3. An error message is friendly if it is business-like and 
informative. 

Discussion: Cute, funny, or flippant messages are to be 
avoided, as they seldom diagnose accurately and always wear 
quickly. Messages should be directed at the process and not the 
person. 

4. Messages must re written plainly, using terms already known to 
the user. 

Discussion: Messages should use terms which are either 
self-defining or natural tc the process. All words should be 
part of the external user interface, like "file name" instead of 
"LFN" (unless LFN is an external parameter). 

5. Messages must be written in English. 

Discussion: Messages should fellow normal rules for English 
grammar and punctuation, although "pidgin English" — the 
omission of selected subjects, verbs or objects in. the interest 
of brevity where the meaning is clear - is acceptable. Messages 
should not be written in octal, or in ether forms of scientific 
notation. Note that the asterisk is net an English punctuator. 
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6. Messages should be self-contained. 

Discussion: If you need to tell a story, tell the vhcle story. 
Avoid references, as they are difficult to keep up-to-date and 
are often no mere helpful then a good one-line message would be. 

7. Error messages should point directly to the source of the 
trouble. 

Discussion: Fcr example, "FILE NOT FOUND" is better put as 
"FILE XYZ NOT FOUND"/ "EXPECTING COMMA CB FEEIOD AFTEB •ABC" is 
much clearer tyban "SYNTAX EBBCB". In general, the technique of 
echoing back part of the user input as part, of the message is 
better than the use of internal names cr parameter keywords 
which ' the user may not reccgni2e. 

8. Interactive error messages should appear as soon as possible 
after an error is committed. 

Discussion: Each interactive input should be completely and 
fully validated as soon as it is received. In no event should a 
user be led down the. garden path to enter a long series cf input 
only to be advised that it is all wrong because the first part 
was wrong. 

9. No messages at all should appear for trivial, correctable errors 
- nor should they be errors . . 

Discussion: Errors such as missing cr redundant terminators 
should not be errors at all. If a reasonable assumption can be 
made as to the intent of an input, it should be acted upon as 
though it were "valid". Nc error diagnostic should be produced 
for these cases. If it is not perfectly clear what assumption 
was made, the assumption was probably net reasonable to begin 
with. 

10. An error message must clearly signal that an error has occurred. 

Discussion: An error message must net be phrased in such a way 
as to be confused with a merely informative message. Also, a 
message should indicate the gravity and extent of the error, as 
when an error in a list inhibits processing cf the remainder 'of 
the list. 
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APPENDIX_C DCCIJKEN1ATI0N/USSEIII1Y_GUICELINES 

1. COMMAND shculd be used instead of CCHTECI STATEMENT cr CONTROL 
CARD. 

2. INCORRECT should be used rather than ILLEGAL or INVALID (refer 
to Appendix E item 1). 

3. USEE should fce used instead of ACCOUNT. 

4. USER NAME should' be used instead of USER NUMBER cr ACCOUNT 
NUMBER. 

5. EXTENDED MEMCEi should be used rather than ECS. 

6. MONITOR REQUEST should be used rather than RA+1 CALL 

7. EST ORDINAL cr DEVICE should be used instead of EQUIPMENT NUMBER 
or EQUIPMENT. ' 

8. English variables such as file name rather than filenam should 
be used to rerccve the shorthand notation of using variable names 
that are the same length as the maximum entry. 

9. Documentation, messages, etc. shculd avoid the use cf sexist 
language (he, she, him, her, etc.). 
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